25.11.3 TeX Printing Commands

You can invoke TeX as an subprocess of Emacs, supplying either the entire contents of the buffer or just part of it (e.g., one chapter of a larger document).

C-c C-b

Invoke TeX on the entire current buffer (tex-buffer).

C-c C-r

Invoke TeX on the current region, together with the buffer’s header (tex-region).

C-c C-f

Invoke TeX on the current file (tex-file).

C-c C-v

Preview the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-view).

C-c C-p

Print the output from the last C-c C-b, C-c C-r, or C-c C-f command (tex-print).

C-c TAB

Invoke BibTeX on the current file (tex-bibtex-file).

C-c C-l

Recenter the window showing output from TeX so that the last line can be seen (tex-recenter-output-buffer).

C-c C-k

Kill the TeX subprocess (tex-kill-job).

C-c C-c

Invoke some other compilation command on the entire current buffer (tex-compile).

To pass the current buffer through TeX, type C-c C-b (tex-buffer). The formatted output goes in a temporary file, normally a .dvi file. Afterwards, you can type C-c C-v (tex-view) to launch an external program, such as xdvi, to view this output file. You can also type C-c C-p (tex-print) to print a hardcopy of the output file.

By default, C-c C-b runs TeX in the current directory. The output of TeX also goes in this directory. To run TeX in a different directory, change the variable tex-directory to the desired directory name. If your environment variable TEXINPUTS contains relative directory names, or if your files contains ‘\input’ commands with relative file names, then tex-directory must be "." or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as "/tmp".

The buffer’s TeX variant determines what shell command C-c C-b actually runs. In Plain TeX mode, it is specified by the variable tex-run-command, which defaults to "tex". In LaTeX mode, it is specified by latex-run-command, which defaults to "latex". The shell command that C-c C-v runs to view the .dvi output is determined by the variable tex-dvi-view-command, regardless of the TeX variant. The shell command that C-c C-p runs to print the output is determined by the variable tex-dvi-print-command. The variable tex-print-file-extension can be set to the required file extension for viewing and printing TeX-compiled files. For example, you can set it to .pdf, and update tex-dvi-view-command and tex-dvi-print-command accordingly.

Normally, Emacs automatically appends the output file name to the shell command strings described in the preceding paragraph. For example, if tex-dvi-view-command is "xdvi", C-c C-v runs xdvi output-file-name. In some cases, however, the file name needs to be embedded in the command, e.g., if you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with ‘*’ in the command string. For example,

(setq tex-dvi-print-command "dvips -f * | lpr")

The terminal output from TeX, including any error messages, appears in a buffer called *tex-shell*. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; see Interactive Shell). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.

Type C-c C-k (tex-kill-job) to kill the TeX process if you see that its output is no longer useful. Using C-c C-b or C-c C-r also kills any TeX process still running.

You can also pass an arbitrary region through TeX by typing C-c C-r (tex-region). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, C-c C-r allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the header.

To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert ‘%**start of header’ before the header, and ‘%**end of header’ after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If ‘%**start of header’ does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.

In LaTeX mode, the header begins with ‘\documentclass’ or ‘\documentstyle’ and ends with ‘\begin{document}’. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.

The commands (tex-buffer) and (tex-region) do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct.

When you want the auxiliary files for cross references, use C-c C-f (tex-file) which runs TeX on the current buffer’s file, in that file’s directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (tex-file) twice to get the cross-references right.

The value of the variable tex-start-options specifies options for the TeX run.

The value of the variable tex-start-commands specifies TeX commands for starting TeX. The default value causes TeX to run in nonstop mode. To run TeX interactively, set the variable to "".

Large TeX documents are often split into several files—one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make tex-file useful when you are editing a subfile, you can set the variable tex-main-file to the name of the main file. Then tex-file runs TeX on that file.

The most convenient way to use tex-main-file is to specify it in a local variable list in each of the subfiles. See File Variables.

For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer’s file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command C-c TAB (tex-bibtex-file) runs the shell command (tex-bibtex-command) to produce a ‘.bbl’ file for the current buffer’s file. Generally, you need to do C-c C-f (tex-file) once to generate the ‘.aux’ file, then do C-c TAB (tex-bibtex-file), and then repeat C-c C-f (tex-file) twice more to get the cross-references correct.

To invoke some other compilation program on the current TeX buffer, type C-c C-c (tex-compile). This command knows how to pass arguments to many common programs, including pdflatex, yap, xdvi, and dvips. You can select your desired compilation program using the standard completion keys (see Completion).